<!--
  ****************************************************************************
  * Copyright 2018-2023,2024 Thomas E. Dickey                                *
  * Copyright 1998-2015,2017 Free Software Foundation, Inc.                  *
  *                                                                          *
  * Permission is hereby granted, free of charge, to any person obtaining a  *
  * copy of this software and associated documentation files (the            *
  * "Software"), to deal in the Software without restriction, including      *
  * without limitation the rights to use, copy, modify, merge, publish,      *
  * distribute, distribute with modifications, sublicense, and/or sell       *
  * copies of the Software, and to permit persons to whom the Software is    *
  * furnished to do so, subject to the following conditions:                 *
  *                                                                          *
  * The above copyright notice and this permission notice shall be included  *
  * in all copies or substantial portions of the Software.                   *
  *                                                                          *
  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  *                                                                          *
  * Except as contained in this notice, the name(s) of the above copyright   *
  * holders shall not be used in advertising or otherwise to promote the     *
  * sale, use or other dealings in this Software without prior written       *
  * authorization.                                                           *
  ****************************************************************************
  * @Id: curs_pad.3x,v 1.61 2024/04/27 17:55:43 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
<HEAD>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
<TITLE>curs_pad 3x 2024-04-27 ncurses 6.5 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">

</HEAD>
<BODY>
<H1 class="no-header">curs_pad 3x 2024-04-27 ncurses 6.5 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>                     Library calls                    <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>




</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
       <STRONG>newpad</STRONG>, <STRONG>subpad</STRONG>, <STRONG>prefresh</STRONG>, <STRONG>pnoutrefresh</STRONG>, <STRONG>pechochar</STRONG>, <STRONG>pecho_wchar</STRONG> - create
       and display <EM>curses</EM> pads


</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
       <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>

       <STRONG>WINDOW</STRONG> <STRONG>*newpad(int</STRONG> <EM>nlines</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>ncols</EM><STRONG>);</STRONG>
       <STRONG>WINDOW</STRONG> <STRONG>*subpad(WINDOW</STRONG> <STRONG>*</STRONG><EM>parent</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>nlines</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>ncols</EM><STRONG>,</STRONG>
             <STRONG>int</STRONG> <EM>begin</EM><STRONG>_</STRONG><EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>begin</EM><STRONG>_</STRONG><EM>x</EM><STRONG>);</STRONG>

       <STRONG>int</STRONG> <STRONG>prefresh(WINDOW</STRONG> <STRONG>*</STRONG><EM>pad</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>pminrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>pmincol</EM><STRONG>,</STRONG>
             <STRONG>int</STRONG> <EM>sminrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>smincol</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>smaxrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>smaxcol</EM><STRONG>);</STRONG>
       <STRONG>int</STRONG> <STRONG>pnoutrefresh(WINDOW</STRONG> <STRONG>*</STRONG><EM>pad</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>pminrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>pmincol</EM><STRONG>,</STRONG>
             <STRONG>int</STRONG> <EM>sminrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>smincol</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>smaxrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>smaxcol</EM><STRONG>);</STRONG>

       <STRONG>int</STRONG> <STRONG>pechochar(WINDOW</STRONG> <STRONG>*</STRONG><EM>pad</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
       <STRONG>int</STRONG> <STRONG>pecho_wchar(WINDOW</STRONG> <STRONG>*</STRONG><EM>pad</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG>


</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
       A <EM>curses</EM> <EM>pad</EM> is like a window, except that it is not restricted by  the
       screen  size,  and is not necessarily associated with a particular part
       of the screen.  Pads can be used when a large window  is  needed,  only
       part  of  which  is  to  be  visible  on  the  screen.   Pads  are  not
       automatically refreshed by scrolling or input-echoing operations.

       Pads  cannot  be  refreshed  with   <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG>;   use   <STRONG>prefresh</STRONG>   or
       <STRONG>pnoutrefresh</STRONG> instead.


</PRE><H3><a name="h3-newpad">newpad</a></H3><PRE>
       <STRONG>newpad</STRONG>  creates  and returns a pointer to a new pad data structure with
       the given number of lines, <EM>nlines</EM>, and columns, <EM>ncols</EM>.


</PRE><H3><a name="h3-subpad">subpad</a></H3><PRE>
       <STRONG>subpad</STRONG> creates and returns a pointer to a subwindow within a  pad  with
       the  given  number  of  lines,  <EM>nlines</EM>,  and  columns,  <EM>ncols</EM>.   Unlike
       <STRONG><A HREF="subwin.3x.html">subwin(3x)</A></STRONG>, which uses screen coordinates, the new  pad  is  placed  at
       position (<EM>begin</EM><STRONG>_</STRONG><EM>y</EM>, <EM>begin</EM><STRONG>_</STRONG><EM>x</EM>) relative to its parent.  Thus, changes made
       to one pad can affect both.  When operating on a subpad,  it  is  often
       necessary  to  call  <STRONG><A HREF="curs_touch.3x.html">touchwin(3x)</A></STRONG>  or  <STRONG><A HREF="curs_touch.3x.html">touchline(3x)</A></STRONG>  on  <EM>parent</EM> before
       calling <STRONG>prefresh</STRONG>.


</PRE><H3><a name="h3-prefresh_pnoutrefresh">prefresh, pnoutrefresh</a></H3><PRE>
       <STRONG>prefresh</STRONG>  and  <STRONG>pnoutrefresh</STRONG>   are   analogous   to   <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG>   and
       <STRONG><A HREF="curs_refresh.3x.html">wnoutrefresh(3x)</A></STRONG>  except that they operate on pads rather than windows.
       They require additional parameters are needed to indicate what portions
       of the pad and screen are involved.

       <STRONG>o</STRONG>   <EM>pminrow</EM>  and  <EM>pmincol</EM>  specify  the  upper  left-hand  corner  of a
           rectangular view of the pad.

       <STRONG>o</STRONG>   <EM>sminrow</EM>, <EM>smincol</EM>, <EM>smaxrow</EM>, and <EM>smaxcol</EM> specify the vertices of  the
           rectangle to be displayed on the screen.

       The lower right-hand corner of the rectangle to be displayed in the pad
       is calculated from the screen coordinates, since the rectangles must be
       the same size.  Both rectangles must be entirely contained within their
       respective structures.  <EM>curses</EM> treats negative values of any  of  these
       parameters as zero.


</PRE><H3><a name="h3-pechochar">pechochar</a></H3><PRE>
       <STRONG>pechochar</STRONG>  is functionally equivalent to calling <STRONG><A HREF="curs_addch.3x.html">waddch(3x)</A></STRONG> followed by
       <STRONG>prefresh</STRONG>.  It suggests to the  <EM>curses</EM>  optimizer  that  only  a  single
       character  is  being  output; a considerable performance benefit may be
       thus enjoyed.  The location of the character <EM>ch</EM> written to the  pad  is
       used to populate the arguments to <STRONG>prefresh</STRONG>.


</PRE><H3><a name="h3-pecho_wchar">pecho_wchar</a></H3><PRE>
       <STRONG>pecho_wchar</STRONG> is functionally equivalent to calling <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG> followed
       by <STRONG>prefresh</STRONG>.  It suggests to the <EM>curses</EM> optimizer that  only  a  single
       wide  character is being output; a considerable performance benefit may
       be thus enjoyed.  The location of the character <EM>wch</EM> written to the  pad
       is used to populate the arguments to <STRONG>prefresh</STRONG>.


</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
       Functions  that  return an integer return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4
       specifies only "an integer  value  other  than  <STRONG>ERR</STRONG>")  upon  successful
       completion.

       Functions  that  return pointers return <STRONG>NULL</STRONG> on error, and set <STRONG>errno</STRONG> to
       <STRONG>ENOMEM</STRONG>.

       X/Open  Curses  does  not  specify  any  error  conditions.   In   this
       implementation

          <STRONG>prefresh</STRONG> and <STRONG>pnoutrefresh</STRONG>
               return an error if the window pointer is null, or if the window
               is not really a pad or if the  area  to  refresh  extends  off-
               screen  or  if  the  minimum  coordinates  are greater than the
               maximum.

          <STRONG>pechochar</STRONG>
               returns an error if the window is not really  a  pad,  and  the
               associated call to <STRONG>wechochar</STRONG> returns an error.

          <STRONG>pecho_wchar</STRONG>
               returns  an  error  if  the window is not really a pad, and the
               associated call to <STRONG>wecho_wchar</STRONG> returns an error.


</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
       <STRONG>pechochar</STRONG> may be a macro.


</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
       BSD <EM>curses</EM> has no <EM>pad</EM> feature.

       SVr2  <EM>curses</EM>  (1986)  provided  the  <STRONG>newpad</STRONG>  and   related   functions,
       documenting  them  in  a  single  line each.  SVr3 (1987) provided more
       extensive documentation.

       The documentation does not explain the term <EM>pad</EM>.  However,  the  Apollo
       <EM>Aegis</EM> workstation operating system supported a graphical <EM>pad</EM> feature:

       <STRONG>o</STRONG>   These  graphical  pads  could  be  much  larger than the computer's
           display.

       <STRONG>o</STRONG>   The read-only output from a  command  could  be  scrolled  back  to
           inspect, and select text from the pad.

       The two uses may be related.

       X/Open  Curses,  Issue 4 describes these functions, without significant
       change from the SVr3 documentation.  It describes no error  conditions.
       The  behavior  of  <STRONG>subpad</STRONG>  if  the  parent  window  is  not  a  pad  is
       undocumented, and is not checked by the vendor Unix implementations:

       <STRONG>o</STRONG>   SVr4 <EM>curses</EM> sets a flag in the <EM>WINDOW</EM>  structure  in  <STRONG>newpad</STRONG>  which
           tells if the window is a <EM>pad</EM>.

           However,  it  uses this information only in <STRONG>waddch</STRONG> (to decide if it
           should call <STRONG>wrefresh</STRONG>) and <STRONG>wscrl</STRONG> (to avoid  scrolling  a  pad),  and
           does  not  check  in  <STRONG>wrefresh</STRONG>  to ensure that the pad is refreshed
           properly.

       <STRONG>o</STRONG>   Solaris <EM>xcurses</EM> checks whether a window is a pad  in  <STRONG>wnoutrefresh</STRONG>,
           returning <STRONG>ERR</STRONG> in that case.

           However,  it only sets the flag for subwindows if the parent window
           is a pad.  Its <STRONG>newpad</STRONG>  function  does  not  set  this  information.
           Consequently, the check will never fail.

           It  makes no comparable check in <STRONG>pnoutrefresh</STRONG>, though interestingly
           enough, a comment in the source code states  that  the  lack  of  a
           check was an MKS extension.

       <STRONG>o</STRONG>   NetBSD  7 <EM>curses</EM> sets a flag in the <EM>WINDOW</EM> structure for <STRONG>newpad</STRONG> and
           <STRONG>subpad</STRONG>,  using  this  to  help   with   the   distinction   between
           <STRONG>wnoutrefresh</STRONG> and <STRONG>pnoutrefresh</STRONG>.

           It  does  not  check for the case where a subwindow is created in a
           pad using <STRONG>subwin</STRONG> or <STRONG>derwin</STRONG>.

           The <STRONG>dupwin</STRONG> function returns a regular  window  when  duplicating  a
           pad.   Likewise,  <STRONG>getwin</STRONG> always returns a window, even if the saved
           data was from a pad.

       This implementation

       <STRONG>o</STRONG>   sets a flag in the <EM>WINDOW</EM> structure for <STRONG>newpad</STRONG> and <STRONG>subpad</STRONG>,

       <STRONG>o</STRONG>   allows a <STRONG>subwin</STRONG> or <STRONG>derwin</STRONG> call to succeed having a  pad  parent  by
           forcing the subwindow to be a pad,

       <STRONG>o</STRONG>   checks  in  both  <STRONG>wnoutrefresh</STRONG> and <STRONG>pnoutrefresh</STRONG> to ensure that pads
           and windows are handled distinctly, and

       <STRONG>o</STRONG>   ensures  that  <STRONG>dupwin</STRONG>  and  <STRONG>getwin</STRONG>  treat   pads   versus   windows
           consistently.


</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
       <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_touch.3x.html">curs_touch(3x)</A></STRONG>



ncurses 6.5                       2024-04-27                      <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-NAME">NAME</a></li>
<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
<ul>
<li><a href="#h3-newpad">newpad</a></li>
<li><a href="#h3-subpad">subpad</a></li>
<li><a href="#h3-prefresh_pnoutrefresh">prefresh, pnoutrefresh</a></li>
<li><a href="#h3-pechochar">pechochar</a></li>
<li><a href="#h3-pecho_wchar">pecho_wchar</a></li>
</ul>
</li>
<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
<li><a href="#h2-NOTES">NOTES</a></li>
<li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
</ul>
</div>
</BODY>
</HTML>
